My Profile_

Introduction

This documentation contains the instructions for integrating Apple Pay as an in-app purchase option using the Moneris Gateway iOS API for Canada. It contains specifications for transaction requests and responses.

System and Skill Requirements

  • XCode 6.3 or higher
  • Knowledge of Objective C or Swift
  • iOS 8.0 or higher

Getting Started With Apple Pay

In order to integrate your Apple Pay In-App payment solution, there are a few basic tasks you have to do to begin:

  1. Boarding your Apple Pay credentials with Moneris
  2. Developing a demo shopping cart application for Apple Pay In-App in order to test functionality
  3. Customizing your project's code to work with the Moneris Gateway

Onboarding In-App

To board your credentials for an Apple Pay In-App solution, there are six basic initial steps:

  1. Registering an Apple merchant ID at the Apple Developer Portal
  2. Downloading a CSR file from the Moneris Merchant Resource Center
  3. Uploading the CSR file to Apple
  4. Downloading a signed Apple Pay Payment Processing Certificate from Apple
  5. Uploading the signed Apple Pay Payment Processing Certificate to the Merchant Resource Center


1. Registering an Apple Merchant ID

The first required step for the boarding process for your Apple Pay In-App is to get a Apple merchant ID on the Apple Developer Portal at developer.apple.com.

2. Downloading a CSR from Merchant Resource Center

Use your Apple merchant ID, also referred to as your Vendor ID, to obtain a client signing certificate (CSR) from the Moneris Merchant Resource Center.

To download your CSR from the Merchant Resource Center:

  1. Go the Moneris Merchant Resource Center at one of the following URLs, depending on your stage of development:

    Testing/QA: https://esqa.moneris.com/mpg
    Production: https://www3.moneris.com/mpg

  2. On the navigation bar at the top, select Admin > Apple Pay
  3. In the fields under the Download CSR section, enter your Apple merchant ID and an email address as a point of contact
  4. Click Download CSR to get the certification signing request (CSR) file from Moneris

3. Uploading the CSR to Apple

Once you have downloaded the CSR from the Moneris Merchant Resource Center, you upload it to the Apple Developer Portal at developer.apple.com.

The CSR from Moneris is required before Apple will issue you a Apple Pay payment processing certificate in the next step.

NOTE: This procedure or some of its details may change at the discretion of Apple, please refer to the Apple Developer Portal for the most up-to-date information.

To upload the CSR to the Apple Developer Portal:

  1. In the Apple Developer Portal, go to Identifiers > Merchant IDs
  2. Under the Apple Pay Payment Processing Certificate section click Create Certificate
  3. Click Continue
  4. In the Generate your certificate step, choose the CSR file from its location and click Upload

4. Downloading a Signed Apple Pay Payment Processing Certificate

After you have uploaded your Moneris Payment Processing CSR to the Apple Developer Portal, Apple gives you the option to download the signed Apple Pay payment processing certificate.

NOTE: This procedure or some of its details may change at the discretion of Apple, please refer to the Apple Developer Portal for the most up-to-date information.

To download the signed Apple Pay payment processing certificate, click Download and save it to your device.

5. Uploading the Signed Certificate to MRC

Once you have the signed Apple Pay Payment Processing Certificate, you upload it to the Merchant Resource Center in order to complete the boarding process for the Apple Pay In-App solution.

To upload the signed Apple Pay Payment Processing Certificate to the Merchant Resource Center:

  1. Select Admin > Apple Pay in the Merchant Resource Center
  2. Under the heading Apple Merchant Certificates, find the row with your Vendor ID (i.e., the Apple merchant ID)
  3. Click the Upload Apple Signed Certificate button in that row
  4. Choose the certificate from its location on your device to upload it.

Developing an Apple Pay Demo App

In order to test the functionality of your Apple Pay solution with the Moneris Gateway, you first need a demo shopping cart application.

Apple provides some examples for Apple Pay In-App on the Apple developer portal for developers to use in integrating their Apple Pay solutions.

For an example of a Apple Pay In-App demo app example:

https://developer.apple.com/library/content/samplecode/Emporium/Introduction/Intro.html

Integrating your demo app with Moneris Gateway

In order for your Apple Pay payment application to use the Moneris Gateway, you need to customize your application code.

In the Apple Pay In-App demo app example, you modify the following files:

ViewController.swift

In the Apple Pay on the Web demo app example, you modify the following files:

index.js
index.html

If you will be processing INTERAC® payments via Apple Pay, there is an additional step. See Enabling INTERAC® e-Commerce Transactions.

Enabling INTERAC e-Commerce Transactions

If your merchant application will be processing INTERAC® e-Commerce debit transactions through Apple Pay, you will need to do additional steps to ensure this feature works.

Before processing INTERAC® e-Commerce transactions, you will also need to have that functionality enabled by your Moneris sales representative.

To enable your Apple Pay integration to process INTERAC® e-Commerce transactions:

  1. Ensure your merchant account with Moneris has INTERAC® e-Commerce functionality turned on; your Moneris sales representative can do this for you
  2. In your payment page code, under the function applePayButtonClicked(), insert 'interac' into the code as shown:

    supportedNetworks:[ 'amex', 'discover', 'masterCard', 'visa', 'interac'],

Transaction Types

Moneris Gateway Apple Pay SDK supports the following transactions:

  • Apple Pay Purchase
  • Apple Pay Pre-Authorization

Once you have processed the initial transaction using Apple Pay Purchase or Apple Pay Pre-Authorization, you can use the Moneris Gateway Unified API or Batch Upload solution to process one of the following supplemental transactions:

NOTE: INTERAC® e-Commerce transaction functionality is currently available only when processing a Purchase transaction.

In addition, the Moneris Gateway Apple Pay SDK also supports optional features, such as Customer Information and recurring transactions.

Apple Pay Token Purchase

The Apple Pay Token Purchase transaction verifies funds on the customer’s card, removes the funds and readies them for deposit into the merchant’s account.

@interface ApplePayTokenPurchase

Required transaction objects – Apple Pay Token Purchase
Variable Name Class Name | Parameters Description
Order Id NSString *orderId Unique transaction identifier issued by the Moneris Gateway
Payment PKPayment *payment Encrypted payload information
Optional transaction objects – Apple Pay Token Purchase
Function Type Class Name | Parameters Description
Customer Information -(void)-setCustInfoWithPayment
NSString *shippingAddress,
NSString *instructions,
NSString *shippingCost,
NSString *tax1,
NSString *tax2,
NSString *tax3		 Customer details such as shipping, taxes, etc. can be sent with a financial transactions such as Apple Pay Token Purchase and Apple Pay Token Pre-Authorization
Recurring billing -(void)-setRecur,
NSString *recurUnit,
NSString *startNow,
NSString *startDate,
NSString *numRecurs,
NSString *period,
NSString *recurAmount		 Recurring Billing is feature which allows for a transaction information to be sent once and then rebilled on a specified interval for a certain number of times.

Apple Pay Token Pre-Authorization

The Apple Pay Token Pre-Authorization verifies and locks funds on the customer’s credit card. The funds are locked for a specified amount of time, based on the card issuer. A subsequent Pre-Authorization Completion transaction must be performed for the funds to settle into the merchant’s account.

This transaction can only be performed on a credit card.

@interface ApplePayTokenPreauth

Required transaction objects – Apple Pay Token Pre-Authorization
Variable Name Class Name | Parameters Description
Order Id NSString *orderId Unique transaction identifier issued by the Moneris Gateway
Payment PKPayment *payment Encrypted payload information
Optional transaction objects – Apple Pay Token Pre-Authorization
Function Type Class Name | Parameters Description
Customer Information -(void)-setCustInfoWithPayment
NSString *shippingAddress,
NSString *instructions,
NSString *shippingCost,
NSString *tax1,
NSString *tax2,
NSString *tax3		 Customer details such as shipping, taxes, etc. can be sent with a financial transactions such as Apple Pay Token Purchase and Apple Pay Token Pre-Authorization
Recurring billing -(void)-setRecur,
NSString *recurUnit,
NSString *startNow,
NSString *startDate,
NSString *numRecurs,
NSString *period,
NSString *recurAmount		 Recurring Billing is feature which allows for a transaction information to be sent once and then rebilled on a specified interval for a certain number of times.

Testing your Solution

For testing your Apple Pay In-App solution, you will need to:

  1. Complete the onboarding process
  2. Get a unique test Store ID and API token
  3. Get Apple merchant ID
  4. Configure code in the MpgRequest object

Getting a Unique Test Store ID and API Token

Transactions requests via the Moneris Gateway API will require you to have a Store ID and a corresponding API token.

For testing purposes, you can either use the pre-existing test stores with the corresponding test API tokens, or you can create your own unique test API token and a unique test store where you will only see your own transactions.

To get your unique Store ID and API token for testing:

  1. Log in to the Developer Portal
  2. In the My Profile dialog, click the Full Profile button
  3. Under My Testing Credentials, select Request Testing Credentials
  4. Enter your Developer Portal password and select your country
  5. Record the Store ID and API token that are given, as you will need them for logging in to the Merchant Resource Center (Store ID) and for API requests (API token).

Alternatively, you can use the pre-existing test stores already set up in the Merchant Resource Center as described in the following section

Test Store Credentials

For testing purposes, you can either use the pre-existing test stores with the corresponding test API tokens, or you can create your own unique test API token and a unique test store where you will only see your own transactions. If you want to use pre-existing stores, use the test credentials provided in the following table.

Store ID API Token MRC Username MRC Password
store1 yesguy1 demouser password
store2 yesguy demouser password
store3 yesguy demouser password
store4 yesguy demouser password
store5 yesguy demouser password

Configuring MpgRequest Object for Testing

To configure the MpgRequest object in your Apple Pay In-App solution for testing:

  1. Insert your test Store ID and test API token
  2. Change the setTestMode value to YES

MpgRequest object code for testing is shown below.

Testing/Development
MpgRequest *req = [MpgRequest
mpgRequestWithStoreId:@"moneris"
ApiToken:@"hurgle"
Transaction:transaction];
[req setTestMode:YES];
[req setProcCountry:@"CA"];

Moving to Production

To move your Apple Pay In-App solution into production you need to:

  1. Complete the onboarding process
  2. Get production Store ID and API token
  3. Get Apple merchant ID
  4. Configure code in the MpgRequest object

Getting a Production Store ID and API Token

In production, you use the Store ID that was given in your activation letter from Moneris. You obtain the production API token from the production Merchant Resource Center.

To get your production API token:

  1. If you have not already done so, activate your production account at

    https://www.moneris.com/activate

    The activation process provides you with your first administrator user for the Merchant Resource Center.

  2. Once activated, log in to the production Merchant Resource Center at

    https://www3.moneris.com/mpg

  3. Select the Admin menu and choose Settings. Your production API token is located under the API token heading on the page.

Configuring MpgRequest Object for Production

To configure the MpgRequest object in your Apple Pay In-App solution for production:

  1. Insert your production Store ID and production API token
  2. Change the setTestMode value to NO

MpgRequest object code for production is shown below.

Production
MpgRequest *req = [MpgRequest
mpgRequestWithStoreId:@"PRODUCTION
STOREID PROVIDED BY MONERIS"
ApiToken:@"PRODUCTION API TOKEN PROVIDED BY MONERIS"
Transaction:transaction];
[req setTestMode:NO];
[req setProcCountry:@"CA"];

Verifying your Transactions

When you send a Preload transaction, you must include a transaction amount and a receipt URL, hosted on your back-end server. The Moneris Gateway sends the transaction response to your receipt URL so that you can verify the amount you sent in the transaction request matches the one coming back in the response from the Moneris Gateway.

As a secondary check, you can also manually look at your transactions in the Moneris Merchant Resource Center.

To use the Merchant Resource Center to verify your transactions have processed:

  1. Log in to the Merchant Resource Center at https://esqa.moneris.com/mpg (testing) or https://www3.moneris.com/mpg (production)
  2. Find your transactions under Reports > Transactions

MpgTransactionRequest Properties

Variable

Limits

Description

Terminal Class Properties

StoreId

10 – character alphanumeric

This is defined and provided by Moneris Solutions and is used to identify the merchant.

NSString storeId

ApiToken

20 – character alphanumeric

This is defined and provided by Moneris Solutions and is used in conjunction with the Store ID to uniquely identify your store.

NSString apiToken

Host

alphanumeric
 

Production

Development / QA

Canada

www3.moneris.com

esqa.moneris.com

NSString host


Request Fields

Mandatory Request Fields

Variable Limits Description
orderId   10 – character alphanumeric Merchant defined unique transaction identifier - must be unique for every Purchase, Authorization and Independent Refund attempts, regardless if they approved or declined.  Must also be unique per merchant account.  For a follow-on transaction (Refunds, Completions, and Purchase Corrections) the order_id must reference the original transaction.
Amount 9 - character decimal (variable length) Amount of the transaction. This must contain at least 3 digits with two penny values. The minimum value passed can be 0.01 and the maximum 9999999.99
payment PassKit Payment Apple Pay payment object returned in the didAuthorizePayment method.  This is passed in the Apple Pay Purchase or Pre-authorization request.
 

Optional CustInfo Request Fields

The customer information section is optional, but if included, all of the fields below are mandatory and must be populated, though they can be populated with a blank value.

Shipping Information

Field Name Size/Type Description
first name 30-character alphanumeric Customer first name
last name 30-character alphanumeric Customer last name
company name 50-character alphanumeric Customer 's company name
address 70-character alphanumeric Customer's address.  Not used for address verification.
city 30-character alphanumeric Customer's city
province 30-character alphanumeric Customer's province or state
postal code 30-character alphanumeric Customer's postal or zip code
country 30-character alphanumeric Customer's country
phone 30-character alphanumeric Customer's phone number
fax 30-character alphanumeric Customer's fax number
tax1 10-character alphanumeric Federal tax amount. Amount is not used for calculating total amount.
tax2 10-character alphanumeric Provincial or state tax amount. Amount is not used for calculating total amount.
tax3 10-character alphanumeric County, local or specialty tax amount. Amount is not used for calculating total amount.
shipping_cost 10-character alphanumeric Shipping cost. Amount is not used for calculating total amount.
Extra Details  
email 60-character alphanumeric Customer email address.
instructions 100-character alphanumeric Instructions or notes.

Optional Recurring Billing Fields

The recurring billing section is optional, but if included, all of the fields below are mandatory and must be populated.

Field Name Size/Type Description
recur_unit day, week, month, eom The unit that you wish to use as a basis for the Interval.  This can be set as day, week, month or end of month.  Then using the “period” field you can configure how many days, weeks, months between billing cycles.  
period numeric 1-999 This is the number of recur_units you wish to pass between billing cycles. Example : period = 45, recur_unit=day -> Card will be billed every 45 days. period = 4, recur_unit=weeks -> Card will be billed every 4 weeks. period = 3, recur_unit=month -> Card will be billed every 3 months. period = 3, recur_unit=eom -> Card will be billed every 3 months (on the last day of the month) Please note that the total duration of the recurring billing transaction should not exceed 5-10 years in the future.  
start_date YYYY/MM/DD This is the date on which the first charge will be billed.  The value must be in the future.  It cannot be the day on which the transaction is being sent.  If the transaction is to be billed immediately the start_now feature must be set to true and the start_date should be set at the desired interval after today.  
start_now true / false When a charge is to be made against the card immediately start_now should be set to ‘true’.  If the billing is to start in the future then this value is to be set to ‘false’.  When start_now is set to ‘true’ the amount to be billed immediately may differ from the recur amount billed on a regular basis thereafter.   
recur_amount 9-character decimal 0.01-999999.99 Amount of the recurring transaction. This must contain 3 digits with two penny values. The minimum value passed can be 0.01 and the maximum 999999.99.  This is the amount that will be billed on the start_date and every interval thereafter.  
num_recurs numeric 1-99 The number of times to recur the transaction.   

Response Fields

Variable Limits Description
ReceiptId 50 – character alphanumeric  The order id specified in the request will be echoed back in the response.  This field is recommended to be displayed on the receipt for tracking and troubleshooting purposes.
ReferenceNum 18 – character numeric This is a bank transaction reference number.  The entire reference number must be displayed on the receipt.  This information should also be stored by the merchant. The following illustrates the breakdown of this field where "660123450010690030” is the reference number returned in the message. Example: 660123450010690030
  • 66012345: Terminal ID
  • 001: Shift number
  • 069: Batch number
  • 003: Transaction number within the batch.
Format: nnnnnnnnnnnnnnnnnn (18 digits)  
ResponseCode 3 – character numeric The response code is used to determine whether the transaction was approved or declined.  The receipt message is determined by the Response Code and the ISO code.

 
Response Code Result
0 – 49 (inclusive) Approved
50 – 999 (inclusive) Declined
null Incomplete


  Custom Apple Pay SDK Responses:
ResponseCode Message Definition
900 Global Error Unable to decrypt payload
  For a full list of response codes and the associated message please refer to the Financial Response Codes.
ISO 2 – character numeric The ISO code is a bank issued response code.  The ISO code and the response code are used to determine the receipt message.
AuthCode 8 – character alphanumeric The authorization code is returned by the issuer as part of the transaction response.  This field must be displayed on the receipt.
TransTime HH:II:SS Processing host time stamp. Time of the transaction.  Must be displayed on the transaction receipt. Format: HH:II:SS  HH = 2 digit hour, 24 hour clock (“0” left padded | 02 = 2am, 14 = 2pm) II = 2 digit minute (“0” left padded) SS = 2 digit seconds (“0” left padded  
TransDate YYYY-MM-DD Processing host date stamp. Date of the transaction.  Must be displayed on the transaction receipt. Format: YYYY-MM-DD  YYYY = 4 digit year MM = 2 digit month (“0” left padded | Jan = 01) DD = 2 digit day of month (“0” left padded)  
TransType 2 – character numeric (variable length) Transaction Type defines what type of transaction was performed.  See below for definitions.  A full description of the type of transaction performed must be displayed on the transaction receipt (Sale, Refund, . . . )

            00 – Sale

            01 – Authorization (Credit Cards only)

Complete true/false Transaction was sent to authorization host and a response was received
Message 100 – character alphanumeric (variable length) Response description returned from issuing institution. The response message indicating in details whether the transaction was Approved or Declined.
TransAmount 9 decimal (variable length) Returns the amount sent in request for processing. The amount represents the amount that the cardholder was charged/refunded.  The amount must be displayed on the receipt. Format: nnnnnnN.NN   The amount will always contain one (1) dollar value and two (2) cent values separated by a period “.”. N = always returned n = returned when required    
CardType 2 – character alphanumeric (variable length) CardType defines the card type used for a transaction.  See below for definitions.  On the transaction receipt the Card Type field must be displayed as “Account” and must be displayed with the full description of the card (Visa, MasterCard . . .)
M = MasterCard 
V = Visa 
AX = American Express 
NO = Novus/Discover in (Canada only)
DS= Discover (US only)
C = JCB (US only)
C1 = JCB (Canada only)
SE = Sears (Canada only)
P = Pin Debit (US only)
D = Debit (Canada only)  
TransID 20 – character alphanumeric (variable length) The transaction number is an identifier used by Moneris Gateway to identify the transaction.  This value is used for follow-on transactions (void, capture, refund).  It does not need to be displayed on the receipt but should be stored in the application database.
TimedOut true/false Transaction failed due to a process timing out
Ticket n/a reserved
DeviceManufacturerIdentifier 12 – character alphanumeric Token requestor ID. Returned from decrypted payload. Hex-encoded device manufacturer identifier.
CAVV 40 – character alphanumeric Decrypted CAVV value for the transaction. Returned for Apple Pay Purchase/Pre-Authorization transaction if payload is successfully decrypted.
CorporateCard                    true/false Indicates whether the card is a corporate card or not
 RecurSucess true/false Indicates whether the transaction successfully registered.
 AvsResultCode 1 – character alphanumeric Indicates the address verification result: Please refer to the AVS Result Codes table for list of possible results.  
 CvdResultCode 2 – character alphanumeric The CVD response is an alphanumeric 2 byte variable. The first byte is the numeric CVD indicator; the second byte would be the response code. The CVD value is keyed on the PINpad when doing a manually keyed transaction.  Please refer to the CVD Result Codes table for list of possible results.
 IsVisaDebit true/false/null Indicates whether the card that the transaction was performed on is Visa debit.
  • true = Card is Visa Debit
  • false = Card is not Visa Debit
  • null = there was an error in identifying the card
 Bank Totals Object
N/A		 Response data returned in a Batch Close and Open Totals request.

Error Messages

Error messages that are returned if the gateway is unreachable

Global Error Receipt – You are not connecting to our servers.  This can be caused by a firewall or your internet connection.  

Response Code = NULL – The response code can be returned as null for a variety of reasons.   A majority of the time the explanation is contained within the Message field.   When a ‘NULL’ response is returned it can indicate that the Issuer, the credit card host, or the gateway is unavailable, either because they are offline or you are unable to connect to the internet.  A ‘NULL’ can also be returned when a transaction message is improperly formatted.

Error messages that are returned in the Message field of the response

Message: XML Parse Error in Request: <System specific detail>
Cause: For some reason an improper XML document was sent from the API to the servlet

Message: XML Parse Error in Response: <System specific detail>
Cause: For some reason an improper XML document was sent back from the servlet

Message: Transaction Not Completed Timed Out
Cause: Transaction times out before the host responds to the gateway

Message: Request was not allowed at this time
Cause: The host is disconnected

Message: Could not establish connection with the gateway: <System specific detail>
Cause: Gateway is not accepting transactions or server does not have proper access to internet

Message: Input/Output Error: <System specific detail>
Cause: Servlet is not running

Message: The transaction was not sent to the host because of a duplicate order id
Cause: Tried to use an order id which was already in use

Message: The transaction was not sent to the host because of a duplicate order id
Cause: Expiry Date was sent in the wrong format

Vault error messages

Message: Can not find previous
Cause: Data key provided was not found in our records or profile is no longer active.

Message: Invalid Transaction
Cause: Transaction cannot be performed because improper data was sent or
Mandatory field is missing or an invalid SEC code was sent.

Message: Malformed XML
Cause: Parse error.

Security Requirements

It is important to note that all Merchants and Service Providers that store, process, or transmit cardholder data must comply with PCI DSS and the Card Association Compliance Programs. However, validation requirements vary by business and are contingent upon your "Merchant Level" or "Service Provider Level". Failure to comply with PCI DSS and the Card Association Compliance Programs 2.0 may result in a Merchant being subject to fines, fees or assessments and/or termination of processing services. Non-compliant solutions may prevent merchants boarding with Moneris Solutions.

As a Moneris Solutions client or partner using this method of integration, your solution must demonstrate compliance to the Payment Card Industry Data Security Standard (PCI DSS) and/or the Payment Application Data Security Standard (PA DSS) 2.0. These standards are designed to help the cardholders and merchants in such ways as they ensure credit card numbers are encrypted when transmitted/stored in a database and that merchants have strong access control measures, logging, secure software updates, secure remote access and support.

For further information on PCI DSS and PA DSS requirements, please visit http://www.pcisecuritystandards.org.

For more information on how to get your application PCI-DSS compliant, please contact our Integration Specialists and download the PCI-DSS Implementation Guide.